Hi:

This is my review of the XCON data model

Document: draft-ietf-xcon-common-data-model-05.txt
Reviewer: Miguel Garcia <miguel.garcia@nsn.com>
Review Date: 4 Sep 2007

1) The the scope of the document is not very clear to me. To be precise, 
I am not totally sure what the model represents. It can be any of:

a) The data in a conference that can be manipulated with a conference 
control protocol.

b) All the exhaustive data needed to instantiate a conference, including 
data manipulated by the conference control protocol, data needed to 
control a mixer, data needed to provide scheduling, notifications, etc.

c) Data needed to provide an extended notification to participants.

I think the aim is 'b', but it is not really clear to me. And this is a 
fundamental question that the document have to answer. I would suggest 
that whatever is the answer, it is clearly written perhaps in the 
abstract and the introduction.

2) The document positions itself as an extension to the conference event 
package (RFC 4575). However, RFC 4575 contains two topics: an event 
package and a data format for such event package. Since the XCON data 
model has little (or nothing) to do with the event package, it would be 
nice to clarify that the XCON data model is an extension to *the data 
format* specified in RFC 4575. This is visible, for example, in the 
Abstract:

    The conference
    information data model defined in this document is an extension of
    (and thus, compatible with) the model specified in the Session
    Initiation Protocol (SIP) Event Package for Conference State.

I suggest rewording, such as:

    The conference
    information data model defined in this document constitutes an
    extension of the data format specified in the Session
    Initiation Protocol (SIP) Event Package for Conference State.

Furthermore: RFC 4575 does not use the term "data model", but instead 
"data format". Please, be precise with the terminology when referring to 
  RFC 4575 (don't refer to the "data model specified in RFC 4575").

3) On the data model itself. Is there a container for the credentials of 
the conference? In PSTN conferences these are typically a conference ID 
number and a PIN. I noticed the <PSTN-ISDN> element has an attribute 
'PIN code', but I am missing the conference ID. On the other side, if 
you have SIP, these could also be a username/password/realm combination 
of the conference. I haven't seen these containers, so... am I missing 
something?

4) Section 1, third paragraph, describes Figure 1 and says:

    A conference control protocol provides
    the interface between a conference and media control client, and the
    conference control server.

I am not sure if I can understand the sense of the sentence. 
Furthermore, I didn't find the "media control client" in Figure 1 or 
defined elsewhere, so probably this is a leftover from the past

5) Section 1, last paragraph:

    The data model defined in this
    document extends the one defined in RFC 4575 [1].

I would say that this document is a "superset" rather than "extends":

    The data model defined in this
    document constitutes a superset of the data format defined in
    RFC 4575 [1].

6) Figure 1.  There are one or more objects called "Conference Object". 
Each one contains just another object called "Conference Information 
Data Model". According to the figure, the Conference Object just 
contains a Conference Information Data model, nothing else, nothing 
more. This makes me thing that both things are the same. Or, in other 
words, perhaps the "Conference information data model" should be removed 
from the figure. Or, if it shouldn't, then you need to describe the 
relation between both in textual form.

7) Section 3.1 starts with a description of the XML elements of the 
model. However, it is not mentioned that some of these elements are the 
same defined in RFC 4575. For example, the text in 3.1 reads:

    All the information related to a conference is contained in
    a <conference-info> element.  The <conference-info> element contains
    the following child elements:
    o  The <conference-description>  ...

Later i the document, it is clearly described that <conference-info>, 
<conference-description> and other elements are those defined in the 
data format in RFC 4575. But is not the case here in Section 3.1, which 
is the main overview. So, please, write it also here. Write a context 
indicating that some elements are those in RFC 4575 and not invented 
here, so that the reader knows where he is.

Once you have created the contact, you can, for example, use the 
adjectives "existing" and "new". You can then refer to the "existing 
<conference-info> element" and a "new <floor-information>  element".

8) I miss a motivation for the existence of roles at the beginning of 
Section 3.2

9) Section 3.2, second paragraph, defines several roles. I guess you 
want to say that a "participant" is the role that provides the user with 
the privilege to send and receive most of the media streams. Similarly, 
and "observer" is the role that provides the user with the privilege to 
receive, but not to send, media. If this is correct, I like these 
definitions above those in the document. Also note that unlike the 
document say, these are not _logical entities_, but *roles*

10) Section 3.2, last paragraph. The normative "SHOULD" and "MAY" have 
no impact in interoperability. So this makes me thing that they aren't 
normative. Proposal:

    If no
    roles are defined for an entity, they should default to
    "participant" but local policy can define an alternative.

11) Section 4, the paragraph above Figure 2: it mentions the XCON-URI 
without a reference to where it is defined. Then I saw it in the IANA 
considerations section, so THIS might be the canonical document that 
defines it. So, I think the XCON URI deserves a section by itself, 
describing the semantics, syntax, etc.


12) Section 4.1, 1st paragraph: Why is there a normative SHOULD in:

    It SHOULD have an extra
    attribute 'xml:lang' to specify the language used in the contents of
    this element as defined in Section 2.12 of [8].

I think it's nice to see the 'lang' attribute, but honestly, the lack of 
it is not going to create an interoperability problem, so I consider the 
SHOULD as a should.

13) Section 4.1, reads:

    The child element <allow-sidebars> describes the capabilities of the
    conference.

I don't think <allow-sidebars> describes any general capabilities of the 
conference.

14) Section 4.1.1: The second paragraph refers to DTSEND and DTSART 
fields without describing what are those. Then later I understood they 
are iCal fields. So please, say it and add a reference to the iCal spec.

15) Section 4.1.1, second paragraph. The <mixing-start-offset> element 
is mixing two semantics: one one side, it indicates whether mixing 
starts according to either a specified time or when a participant with a 
role joins. I think it would much clear to create three elements 
instead: one is a <mixing-start>, which can take the values "by-time", 
"by-joining-role", or "at-first-join". Another would be the existing 
<mixing-start-offset>, which would be restricted to indicating a time, 
and only available when <mixing-start> takes the value "by-time". A 
third one is <mixing-start-role> which would take the values 
"participant", "moderator", "administrator", and is only available is 
<mixing-start> takes the value "by-joining-role".

16) First paragraph in Section 4.1.5. The text reads:

    The 'name' attribute identifies a
    codec, and the 'decision' attribute contains the policy for that
    codec (allowed, or disallowed).

I suspect you cannot write a free text in the 'name' attribute. Most 
probably you want to say that the list of possible codecs is controlled 
by some IANA registry. I suspect that you are looking at the 'encoding 
name' column in the IANA registry for RTP Payload Types, 
http://www.iana.org/assignments/rtp-parameters

Most likely you also have to take into account the 'subtype' column of 
the RTP Payload Format media types per [RFC4855] available in the same 
IANA web page.

17) Section 4.1.5, last paragraph describes the <mix-level> attribute. I 
am sorry to say, but it was hard to understand what this is. I still 
have my doubts. So... for example, in an audio stream. In a conference 
with 50 participants, if <mix-level> takes the value 3, which 3 input 
streams are input to the output stream?

Similarly, in a video stream. If <mix-level> takes the value 5, then how 
does this affect the output stream and which 5 input streams are selected?

18) Same section 4.1.5 last paragraph. The text reads:

    The <mixing-mode> child element MUST contain one and
    only one of the "Moderator-controlled", "FCFS", and "Automatic"
    values indicating the default algorithm to be use with every media
    stream.

Can you please describe the semantics of these values? Since I 
understand (a bit of) English, I more or less can figure out what you 
mean. But think for a while if these identifiers would be just called 
id1, id2, and id3 and try to explain them.

19) Section 4.1.5.1.1 defines the <mute> element and Section 4.1.5.1.2 
defines the <pause-video> element. I think these two are very similar, 
the only difference being that the former applies to audio streams, the 
latter to video streams. I would like to see a single element, perhaps 
called <output-stream-enabled> or something like that. This could apply 
for any kind of media stream, even for MSRP.

20) Section 4.1.5.1.3 defines the <gain> element. I am missing 
attributes that defines the minimum and maximum levels. Without it, if I 
get that the mixing level is 10, I have now idea if it is 10 in a scale 
1-10, 10 in a scale 1-100, or 10 in a scale 1-1000. Further more, 
without the maximum/minimum level, it wouldn't be possible to create a 
UI scale representation, making the control totally useless.

21) Section 4.1.5.1.4 defines the <video-layout> element. One possible 
value is 'multiple-5x1', where "one panel will occupy 4/9 of the mixed 
video stream while the others will each occupy 1/9 of the stream". My 
question is: how to select the input video stream that will go into the 
big panel? And how to select each of the other video streams, if you 
have, say, 20 input video streams? The same is applicable for any 
video/audio stream where there more inputs than possible outputs.

And how does this element interact with the <mixing-level> element? It 
seems that the <mixing-level> indicates a pure maximum number of inputs, 
where I think it is irrelevant when you have a <video-layout> element.

For example, what is the meaning of having both:
    <mix-level>automatic</mix-level>
    <controls>
        <video-layout>automatic</video-layout>
    </controls>

22) More on Section 4.1.5.1.4. The last paragraph defines the 
'automatic' value as:

    automatic: This option allows the focus to add panels as streams are
    added up to a limit of "panels".

What is this 'limit of "panels"'? Is it a local policy? In either case, 
I think there should be means to configure this maximum number of 
panels, so I am missing a "max-panels" attribute or something like that.

23) Section 4.4, first paragraph describes the <floor-information> 
element and says:

    This element has its own XML namespace.

What is this own XML namespace. Which one is it? Where is specified? Why 
none of the examples show any namespace?

24) Section 4.4, second paragraph tries (but fails) to define the 
<conference-ID> element:

    The <conference-ID> is used by a floor control server to provide a
    client with a conference ID.

The text says how is this used, but doesn't say what it is and how it 
differentiates from the other zillions conference identifiers we already 
have. So please first explain what is this element, how is it different 
from other similar ones, and then you keep the explanation of how it is 
used (which I haven't understood so far).

25) Section 4.4, 5th paragraph reads:

    Note that placing a value of "block" for this element does not
    guarantee that a participant is blocked from joining the conference.

Although the spirit of the text is to avoid misleading the user, it just 
got the opposite effect. I am aware we are discussing floor control 
issues, so bringing here the concept of joining a conference created a 
restart in my mind. I would suggest to either delete or rephrase it better:

    Note that this section discusses floor control information, 
therefore, the value "block" in a <floor-request-handling> element is 
not related with the "block" value in the <join-handling> element (see 
Section 4.5).

26) Same paragraph in Section 4.4 reads:

    Any other rule that might evaluate to TRUE for this participant that
    carried an action whose value was higher than "block" would
    automatically grant confirm/allow permission to that participant.

First, the text seems to imply that there are some precedence order 
between several values, but does not say which are those values. If such 
precedence order exists, it probably needs to be specified, otherwise, 
users will have unexpected behaviors depending on the manufacturer of 
the conference server.

Second. Is the paragraph true? Can you give an example of "other rule 
that might evaluate to TRUE for this participant" that would grant 
confirm permission instead of block?

Third: Which participant this rule applies? I didn't find an element to 
specify participants in <floor-request-handling>, so I don't understand 
anything.

27) Section 4.4, 6th paragraph: The text reads:

    The <conference-floor-policy> element is mandatory and contains the
    required boolean attribute that indicates if the floor is moderator
    controlled or not.

Please mention the name of the attribute, which I believe is 
'moderator-controlled'

Second and more important thing: I think the schema makes 
'moderator-controlled' an attribute of <floor>, not an attribute of 
<conference-floor-policy> as the text suggest.

28) Same section and topic: I noticed that 'moderator-controlled' can be 
either an attribute of <conference-floor-policy> or a value in the 
<algorithm> element. I would suggest to rename one to avoid collisions 
between attributes and values of elements.

29) Same section 4.4, still 6th paragraph:

    Every floor is defined using the 'label' attribute.

I would say that floors are not _defined_, but _identified_, using the 
'label' attribute. Also, the schema says 'label' is mandatory, so say it:

    Every floor is identified by the mandatory 'label' attribute.

30) Same section 4.4, still 6th paragraph:

    A floor can be used for one
    or more media types; the mandatory <media-types> element can contain
    zero or more of the <video>, <audio>, <application>, <data>
    ,<control>, <message>, and <text> elements indicating the media of
    the floor.

I don't understand why do you need to repeat all this information here:

- You have the <floor> element with the 'label' attribute. The 'label' 
attribute is a sort of indirect reference to 'label' attribute with the 
same value of the <entry> element, which is part of <available-media>. 
So, I don't see the value in having the <media-types> element here.

In any case, bear in mind that there is an error because the so-called 
<video>, <audio>, etc... are not elements, but textual choices, in the 
schema.


31) Same Section 4.4., still 6th paragraph:

I don't understand how to specify a floor that controls two media 
streams. So, assume a floor that controls the audio and video streams, 
identified by 'label' attributes 10234 and 10235 respectively (like in 
the example).

The problem is that attributes in XML do not accept repetition, so the 
'label' attribute in <floor> contains either 10234 or 10235, but not 
both. So how would this be? I think the following is incorrect, because 
there is no way to correlate the floor with the exact video stream 
specified in the <available-media>.

    <floor moderator-controlled="true" label="10234">
      <media-types>audio</media-types>
      <media-types>video</media-types>

If you need repetition, then turn the 'label' attribute into a child 
element, in which case I also suggest to change the name to something 
different than the existing 'label' attribute, perhaps, <media-label>

31) Same Section 4.4., 7th paragraph:

    the mandatory
    <algorithm> element MUST contain one and only one of the <moderator-
    controlled>, <FCFS>, and <random> elements indicating the algorithm.

But the schema says that moderator-controlled, FCFS and random are 
choices of possible values, so, they text should say:

    the mandatory
    <algorithm> element MUST be set to any of the 
"moderator-controlled", "FCFS" or "random" values indicating the algorithm.

And when you have done it, please indicate what those values mean. 
Again, imagine they are named "alg1" "alg2" and "alg3" and try to 
explain their meaning.

32) Still Section 4.4. Last paragraph:

    The optional <chair-id> indicates
    the BFCP UserID of the moderator.

What is the 'BFCP UserID'? I am looking at RFC 4582 and I don't find 
such term there. There is a 'User ID', but it looks more like a string 
or integer. However, the schema says this is a URI (so it does the 
example). So there is an underspecified field that needs further 
clarifications.

33) Same paragraph as before:

    The optional <chair-id> indicates
    the BFCP UserID of the moderator.

The text introduces a mismatch between "chair" and "moderator". Are 
those the same role? While BFCP speaks about the "chair" role, this 
draft speaks about the "moderator" role. Somehow, I think the 
terminology should be consistent, and perhaps this is a <moderator-id>.

34) Section 4.5, second paragraph, "IVR":

    o  "IVR": This action instructs the focus that the user has to
       provide the PIN code.

First, an issue of the terminology: while the other values represent 
verbs with an action (block, allow, confirm, etc.), this one represents 
the name of a functional entity). It makes no sense. Perhaps you are 
looking for "provide-credentials" or something like that.

Second, as indicated later, I don't think this should be restricted to a 
PIN code. This could well be a username/password combination supplied by 
SIP HTTP Digest authentication. I am not sure if you need to distinguish 
the PIN versus SIP-digest. If needed, you an add an optional attribute.

35) Section 4.5, third paragraph:

    Note that placing a value of block for this element does not
    guarantee that a participant is blocked from joining the conference.


No??? Really? So what the heck do I need to do to prevent a participant 
from joining the conference? The text seems to suggest a higher 
precedent control, but fails to indicate which one it is.

36) Section 4.6, 4th paragraph speaks about the <user-admission-policy>.

Can you please list all the possible values in an unordered list, like 
the one you have for <join-handling>? This disposition will make it 
easier to read.

37) Figure 4 contains a Conference User Identifier.

Is the Conference User Identifier a user selected id? I guess not. Is it 
visible in any protocol or can it be manipulated by someone? I guess 
not. So I don't get the purpose of it and why is it visible in the model.

38) RelaxNG and RFC 4575.

I don't understand very well RelaxNG. But I was expecting that this 
document imports or includes (or whatever is the action in RelaxNG) the 
4575 namespace, so that the elements and attributes defined there need 
no new definition.

This seems to be the namespace mapping in Section 5:

    namespace a = "http://relaxng.org/ns/compatibility/annotations/1.0"
    namespace local = ""
    namespace ns1 = "urn:ietf:params:xml:ns:conference-info-urn"
    default namespace ns2 = "urn:ietf:params:xml:ns:conference-schema"

Then, 'ns1' is not use other than at the end of the document for 
something I don't really understand:

    # WILDCARD FOR EVENT-PACKAGE NAMESPACE
    conference-info-urn =
      element ns1:* {
        (attribute * { text }
         | conference-info-urn)*
      }


My point is: Are the elements and attributes defined in RFC 4575 the 
same (imported) as those the with same name specified in this document? 
If they are, where is the link in the namespace, that I am missing?

39) Section 7, Example:

  <?xml version="1.0" encoding="UTF-8"?>
    <conference-info xmlns="urn:ietf:params:xml:ns:conference-schema"


This is somehow related to the previous point: Where is the namespace 
defined in RFC 4575, which is 
xmlns="urn:ietf:params:xml:ns:conference-info"?

I was expecting that all the elements imported from RFC 4575 have to be 
identified as part of that namespace.

40) Section 7, Example:

  <?xml version="1.0" encoding="UTF-8"?>
    <conference-info xmlns="urn:ietf:params:xml:ns:conference-schema"
        entity="conference123@example.com" state="full">

According to RFC4575 the 'entity' attribute is a SIP URI, but not here. 
Are those 'entity' attributes the same objects?

41) Section 7, Example:

        <conference-description xml:lang="en-us">

            <security-level>low</security-level>
            <allow-sidebars>true</allow-sidebars>
            <conference-stage>running</conference-stage>

What are these <security-level> and <conference-stage> elements?

42) Section 7, Example

Although the schema does not mandate the presence of a 
<user-admission-policy> element (child of <users>), I think it would be 
valuable to have it in the example. I suggest to add it.

43) Section 7, Example:

In USER ALICE, there is a strange element:

                <sphere value="work"/>


44) Section 7, Example

In SIDEBARS BY REFERENCE there are a couple of GRUUs containing the old 
'grid' parameter. First a question, do they need to be GRUUs? If they 
need, please add a discussion in the text and update the syntax with 
that of the current version of GRUU.

45) Section 9.3 contains the conference object identifier registration.

First, the title of the section refers to the identifier, but it is 
registering a URI. So this should be updated.

Second, and more important. This came once more out of the blue, with 
little of no discussion in the document of how to use this URI

Third, if still needed, which is not clear to me, you need to make the 
syntax compatible with RFC 3986. To be precise, 'hostport' is deprecated 
and replaced by 'host [ ":" port ]', where both 'host' and 'port' are 
specified in RFC 3986.

46) Missing registries?

I was wondering if you need an IANA registry for each of those 
enumerated values. For example, take the <mix-mode> element, which can 
currently take three values: moderator-controlled, FCFS, and automatic. 
What happens if in the future someone develops a mixing mode called 
'louder-voice'. I think it should be registered with IANA and extend the 
model.

On doing so, you need to think of the extensibility mechanisms for 
RelaxNG (which I don't really know), and the policy for such extensions.

47) Normative references. I am missing RFC 3986 and a reference to 
RelaxNG in the Normative references.

48) Section 4.1.1, last paragraph:

    The <allowed-
    extend-mixing-end-offset> refers to the possibility to extend the
    conference.  It has two values: "allowed", "denied".

I don't think the schema restricts the list of values to "allowed" and 
"denied". But I also think this should be a boolean value. At least 
other <allow*> elements are boolean.




49) Typo in Section 4, 3rd paragraph: s/complimentary/complementary

50) Typo in the last paragraph in Section 4.1.2: The attribute 'PIN 
code' is written in the schema with a dash: 'PIN-code'

51) Section 4.4, first paragraph
Replace:
The <floor-information> element has the <conference-ID>

with:
The <floor-information> element contains the <conference-ID>

52) Section 4.5.1, last paragraph:

s/difference/different


53) Section 7, Example:


            <conference-time>
                <entry>
                    <base>BEGIN:VCALENDAR


                     <mixing-start-offset required-participant="moderator"
                        > 2007-10-17T14:29:00Z</mixing-start-offset>
                    <mixing-end-offset required-participant="participant"
                        > 2007-10-17T16:31:00Z</mixing-end-offset>
                    <must-join-before-offset
                        > 2007-10-17T15:30:00Z</must-join-before-offset>

Is the white space in between ">" and "2007" correct? I think it 
shouldn't be there?

s/> 2007/>2007

54) Section 7, Example:

            <conf-uris state="full">
                <SIP>
                    <uri>tel:+3585671234</uri>
                    <display-text>Conference Bridge</display-text>
                    <purpose>participation</purpose>
                </SIP>
                <SIP>
                    <uri>http://www.example.comlive.ram</uri>

Need a "/" to separate the hostname from the file in the last URI:

                    <uri>http://www.example.com/live.ram</uri>



------- end of review --------

/Miguel



-- 
Miguel A. Garcia           tel:+358-50-4804586
Nokia Siemens Networks     Espoo, Finland


_______________________________________________
XCON mailing list
XCON@ietf.org
https://www1.ietf.org/mailman/listinfo/xcon